Read
The Read command reads data from a file, starting from the file mark and continuing to the end of the file.Read is one of several commands provided by the Read/Write Commands scripting addition. For more information about using these commands and sample scripts, see "Using Read/Write Commands,".
SYNTAX
read referenceToFile [ from startingByte ] ¬ [ for bytesToRead | to byteToReadTo ¬ | until delimiterIncluded | before delimiterExcluded ] ¬ [ as className [ using delimiter[s] delimiters ] ]PARAMETERS
- referenceToFile
- A reference of the form
filenameString oraliasnameString, or a file reference number previously obtained with the Open for Access command (see "Notes").
Class: Reference or integer
- startingByte
- The offset of the byte from which to begin reading. A positive integer indicates the offset from the beginning of the file, and a negative integer indicates the offset from the end of the file.
Class: Integer
- bytesToRead
- The number of bytes to read. If the
fromstartingByte parameter is included, the Read command reads bytesToRead bytes starting at the specified starting point; otherwise, the Read command begins reading at the file mark. If the value of this parameter is negative, an error occurs.
Class: Integer
- byteToReadTo
- The offset of the byte to read to. If the
fromstartingByte parameter is included, the Read command reads from the specified starting point to byteToReadTo; otherwise, the Read command begins reading at the file mark. A positive integer indicates the offset from the beginning of the file, and a negative integer indicates the offset from the end of the file.
Class: Integer
- delimiterIncluded
- A delimiter (such as a tab or return character) to read to. The specified delimiter is included in the read (unless it is an end-of-file delimiter, which is not included). If the
fromstartingByte parameter is included, the Read command reads from the specified starting point to the specified delimiter; otherwise, the Read command begins reading at the file mark.
Class: String
- delimiterExcluded
- A delimiter (such as a tab or return character) to which to read. The specified delimiter is not included in the read. If the
fromstartingByte parameter is included, the Read command reads from the specified starting point to the specified delimiter; otherwise, the Read command begins reading at the file mark.
Class: String
- className
- The class of the data to be read. The Read command reads the number of bytes appropriate for a value of the class specified by this parameter. (For details, see "Notes" later in this definition.)
Class: Class
- delimiters
- If the data being read is text-based, you can use this parameter to specify the delimiters the Read command should use when interpreting the data as values of the class specified by className. (For details, see "Notes" later in this definition.)
Class: String or constant, or a two-item list of strings or constantsRESULT
If the Read command is successful, it returns the data read from the file as text (unless specified otherwise by theasparameter).EXAMPLES
This example reads MyFile from the 12th byte and to the end of the file.
read file "Hard Disk:MyFile" from 12The next example reads MyFile from the 12th byte before the end of the file to the end of the file.
read file "Hard Disk:MyFile" from -12The next example reads 24 bytes of MyFile starting at the 12th byte. If the end of the file is reached before 24 bytes have been read, an error is returned.
read file "Hard Disk:MyFile" from 12 for 24The next example reads MyFile starting at the end of the file and reading backward until the third byte from the end.
read file "Hard Disk:MyFile" from -1 to -3If the last characters of file MyFile were "123456", the preceding example would return"654".NOTES
The file mark is a marker used by the File Manager that indicates the byte at which the Read command expects to begin reading data. By default, the file mark is the first byte of the file. However, running a script like this causes the file mark for MyFile to be moved:
read file "Hard Disk:MyFile" from 1 to 4The file mark for MyFile is now at byte 5, so the next Read command in the same script begins at byte 5. For example, the command
read file "Hard Disk:MyFile" for 4reads bytes 5 through 8.To specify the name (nameString) of a file, use a string of the form
"Disk:Folder1:Folder2:...:Filename"as described in Chapter 5, "Objects and References," of the AppleScript Language Guide. If you specify only the name of the file (Filename) instead of its entire pathname, AppleScript attempts to find the file in the current directory.If you specify a reference to a file or an alias, the Read command attempts to match the reference with a file previously opened with the Open for Access command. If a match is found, it simply reads the specified data. If no match is found, the Read command opens the file, reads the specified data, then closes the file. The file mark for a file opened in this fashion is always at the beginning of the file.
If you specify a file reference number previously obtained with the Open for Access command, the Read command reads the specified data immediately.
You can use the as className parameter to specify how the Read command should interpret the data it reads. If data to be read is not a valid value for the specified value class, the Read command returns an error. The rest of this section describes some of the value classes you can specify and the nature of the data returned if the Read command reads the data successfully.
as list- The Read command returns a list only if the data to be read was written to disk as an AppleScript list. If the data to be read is delimited text, you can specify the delimiters used in the data with the
using delimiterparameter, and the Read command creates an AppleScript list based on those delimiters.- For example, this script returns a list of items from MyFile using both tab and return characters in MyFile to separate each item in the list:
read file "Hard Disk:MyFile" as {text} ¬ using delimiters {return, tab}You can also specify other types by enclosing the appropriate four-character code in quotation marks. Here's an example.
- The resulting list, like any other AppleScript list, is comma- delimited. You can't specify more than two delimiters; if you do, Read returns the error -50.
as record- Read returns a record only if the data being read was written to disk as an AppleScript record. Read can't coerce other values
to records.
as integer- If the data consists of a single integer, Read returns the integer. If the data consists of more than one integer, Read returns a list
of integers.
as text- Read returns the data as a string. This is the default behavior if the as className parameter is omitted.
as real- If the data consists of a single real number, Read returns the real number. If the data consists of more than one real number, Read returns a list of real numbers.
as short- The short value is defined by the Read/Write Commands scripting addition as 2 bytes long. This can be is useful if you are reading data from a file that uses short integers rather than the 4-byte integers defined by AppleScript. Read interprets the data as one or more discrete 2-byte values. If the data consists of more than one short value, Read returns a list of shorts. If the data is text, you can specify the delimiters used in the data with the
using delimiterparameter, and the Read command attempts to coerce each item between delimiters to a short.
as boolean- If the data consists of a 1-byte Boolean value, Read returns the Boolean value. If the data consists of more than one Boolean value, Read returns a list of Boolean values.
as data- Read returns the data as an uninterpreted stream of hexa-
decimal bytes.
read file "Hard Disk:myFile" as "PICT"--returns data as type 'PICT'ERRORS